一、TDD（Test-Driven Development，測試驅動開發）是什麼？

TDD（Test-Driven Development，測試驅動開發）是一種以「先寫測試、後寫程式」為核心的開發方法。傳統開發往往先撰寫功能，再事後補上測試；而在 TDD 中，開發流程被刻意反轉。

先想清楚「期望程式行為」並以測試程式的方式描述它，然後再讓開發程式碼去通過這個測試。這個循環通常簡稱為 Red–Green–Refactor：

• Red：先撰寫一個會失敗的測試，確認目前功能尚不存在。
• Green：撰寫最小量的程式碼，使測試通過。
• Refactor：優化程式結構，保持測試綠燈狀態。

測試流程示意表（紅 → 綠 → 藍）

TDD 的價值不僅在於提升測試覆蓋率，更重要的是它能引導開發者以「需求」為中心思考設計。因為測試事先定義了介面與期望結果，開發者在實作階段能明確知道「什麼是足夠的功能」，也能更容易拆分問題、重構程式，減少未來維護的難度。

以資料庫功能為例，TDD 會先定義出資料的 CRUD 行為測試（例如「新增使用者後能成功查詢出來」），再逐步實現每個資料操作。這種流程讓開發者能及早發現邏輯錯誤、結構不合理或資料設計問題。

二、一般開發 vs 測試驅動開發（TDD）

三、TDD 資料庫設計規劃

• Flask — Web 應用框架
• Flask-SQLAlchemy — ORM 層
• pytest — 單元測試框架
• SQLite — 測試階段使用 in-memory 資料庫

四、設計原則

在 TDD 模式下，每個設計決策都須具備「可測試性」。
以下為本專案設計的三大原則：

1. 簡潔性（KISS）

   • 將可變結構（例如營養分析細項）以 JSON 字串儲存在欄位 nutrients_json。
   • 在初期 POC 階段避免建立過多關聯表，以快速驗證邏輯正確性。

2. 可測試性（Testability）

   • 測試環境使用 sqlite:///:memory:，確保每個測試函式皆獨立、快速且不干擾其他案例。
   • 以工廠函式或動態建立 app 的方式進行初始化。

3. 最小可行實作（MVP）

   • 先撰寫測試案例，定義預期行為。
   • 僅在測試失敗（紅燈）時進行最小修改以通過測試（綠燈）。
   • 通過後再進行程式結構優化（重構階段）。

五、資料模型設計構想

目標模型：AnalysisRecord

此模型對應一筆 AI 食物分析結果，包含原始資料、摘要、營養成分等欄位。

此外，會提供對應的 nutrients 屬性，
讓開發者可直接以 Python 結構（list/dict）操作，而非手動處理 JSON 字串。

六、本專案具體執行步驟：

1. 定義測試規格（CRUD 與 JSON 欄位操作）。
2. 撰寫 tests/conftest.py 與 tests/test_models.py。
3. 執行 pytest，觀察錯誤訊息。
4. 實作 models.py 內的最小邏輯（nutrients property、timezone-aware 時間欄位）。
5. 修正過時 API (Model.query.get → db.session.get)。
6. 反覆測試直到所有測試通過且無警告。

七、測試規格

測試案例需驗證以下行為：

八、測試環境設定（tests/conftest.py）

此檔案負責建立 Flask 測試應用與測試資料庫。

import pytest
from flask import Flask

try:
    from app import create_app as _create_app
except Exception:
    _create_app = None

try:
    from models import db as _db
except Exception:
    _db = None

@pytest.fixture(scope="function")
def app():
    """建立測試用 Flask App，使用 in-memory SQLite"""
    config = {
        "TESTING": True,
        
        # 使用 `sqlite:///:memory:` 讓測試資料存在記憶體中。
        "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:",
        "SQLALCHEMY_TRACK_MODIFICATIONS": False,
    }

    if _create_app is not None:
        app = _create_app(config)
    else:
        app = Flask(__name__)
        app.config.update(config)
        if _db is None:
            raise RuntimeError("找不到 models.db，請確認 models.py 有定義 db = SQLAlchemy()")
        _db.init_app(app)

    with app.app_context():
        _db.create_all()
        yield app
        _db.session.remove()
        _db.drop_all()

@pytest.fixture
def db(app):
    """提供資料庫 session 給測試案例"""
    return _db

補充說明

• 每次測試執行前後皆自動建立與銷毀資料表。

九、主要測試檔案（tests/test_models.py）

import json
from models import AnalysisRecord, db

def test_analysisrecord_crud_and_nutrients_json(db):
    """測試 CRUD 與 JSON 欄位行為"""
    rec = AnalysisRecord(
        image_path="uploads/test_apple_pie.jpg",
        raw_analysis="{\"ai\":\"result\"}",
        summary="蘋果派 測試"
    )
    rec.nutrients = [
        {"nutrient": "calories", "value": 250},
        {"nutrient": "fat", "value": 12.5}
    ]

    db.session.add(rec)
    db.session.commit()

    # 查詢
    found = AnalysisRecord.query.filter_by(image_path="uploads/test_apple_pie.jpg").first()
    assert found is not None
    assert found.summary == "蘋果派 測試"
    assert isinstance(found.nutrients, list)
    assert found.nutrients[0]["nutrient"] == "calories"

    # 驗證 JSON 結構
    parsed = json.loads(found.nutrients_json)
    assert parsed[1]["value"] == 12.5

    # 更新
    found.summary = "更新摘要"
    db.session.commit()
    updated = db.session.get(AnalysisRecord, found.id)
    assert updated.summary == "更新摘要"

    # 刪除
    db.session.delete(updated)
    db.session.commit()
    assert db.session.get(AnalysisRecord, found.id) is None